README.TXT
==========
What is SimplePrintout?
=======================
This directory contains a very simple printing class.
SimplePrintout unit provides a very basic printout for your
quick and dirty Delphi for .NET projects. Many times when
you sit down to write a tiny software project you feel like
there is no easy way of printing out relatively small amounts
of data.
Of course, .NET makes it easier to print text and pictures. However
the first time you need to print justified text or bordered text, or
pages with simple header or footer, you come to realize that you
still have to revert to counting pixels.
In many cases using a professional report generating tools
may be an overkill, but writing your own printing component
can be a daunting task too.
That is where SimplePrintout class comes into play.
SimplePrintout keeps all those details hidden from you. Although
it is not a full-blown reporting tool, you will be amazed just
how much you can accomplish with this little unit...
Installation
============
At the time of this writing SimplePrintout for Delphi for .NET
has some minor problems with code serialization. I need to clean
that up to make it into a component. So for now SimplePrintout
is provided as a Delphi unit, rather than an installable component.
As a result, it does not require any installation. Simply copy the
unit called Simp_Prn.PAS to your project directory and add
"Simp_Prn" to your unit's USES statement.
Don't forget to check Borland CodeCentral for the latest code
updates.
How to use SimplePrintout component?
====================================
The best way to find out about SimplePrintout is to compile and
run the DemoProj application. This demo application will get
you started.
Lesson 1.
--------
You may simply create and use an instance of SimplePrintout at
runtime. It is relatively easy. Start by adding "Simp_Prn" unit
to your "uses" stament.
procedure TWinForm.Button1_Click(sender: System.Object;
e: System.EventArgs);
VAR p: SimplePrintout;
s: StreamReader;
begin
// It's very simple to create
// a SimplePrintout...
//
p := SimplePrintout.Create();
try
// Always call BeginPrintout!
//
p.BeginPrintout();
// And finally here is how to print out a text file...
// This is much simpler than Microsoft .NET sample.
//
s := StreamReader.Create('c:\autoexec.bat');
p.WriteString(s.ReadToEnd());
s.Close();
// Use this call to flush the text to the printer
//
p.EndPrintout();
// NOTE: To cancel printout you may use
// p.AbortPrintout(); instead of p.EndPrintout();
//
except
on E: Exception do
MessageBox.Show(E.Message);
end;
p.Free; // with .NET you do not really need this one
end;
Lesson 2.
--------
Let us add some meat to our sample code...
procedure TWinForm.Button1_Click(sender: System.Object;
e: System.EventArgs);
VAR p: SimplePrintout;
s: StreamReader;
begin
p := SimplePrintout.Create();
try
// Always call BeginPrintout!
//
p.BeginPrintout();
// You may set margins (measured in inches)
//
p.TopMargin := 1.5; // leave some room for the header
p.BottomMargin := 1; // leave some room for the footer
// It is pretty easy to set footers and headers...
//
p.Header.Text := 'you can have'+#13#10+'multi-line HEADERS';
p.Footer.TextIndentBottom := 0.3;
p.Footer.Text := 'Footer text';
// To align your paragraph text to Left,
// simply set Band.TextAlignment to baLeft
// (Your choices for alignment are:
// baLeft, baRight, baCentered, and baJustified
//
p.Band.TextAlignment := BandAlignment.baLeft;
// This is how you can change fonts.
// It's pretty striaghtforward.
//
p.Band.TextFont := System.Drawing.Font.Create('Arial', 12);
// And finally here is how to print out a text file...
// This is much simpler than Microsoft .NET sample.
//
s := StreamReader.Create('c:\autoexec.bat');
p.WriteString(s.ReadToEnd());
s.Close();
// Use this call to flush the text to the printer
//
p.EndPrintout();
// NOTE: To cancel printout you may use
// p.AbortPrintout(); instead of p.EndPrintout();
//
except
on E: Exception do
MessageBox.Show(E.Message);
end;
p.Free; // with .NET you do not really need this one
end;
Lesson 3.
--------
How to add Page numbering to the footer (or header). Or rather,
let us paraphrase this question. How to make headers and footers
more dynamic?
All you need is to add an event handler like this:
procedure TWinForm.on_PrintPage(sender: System.Object;
ua: UserPrintPageEventArgs);
begin
(sender as SimplePrintout).Footer.Text :=
'Page ' + ua.PageNo.ToString;
end;
procedure TWinForm.Button1_Click(sender: System.Object;
e: System.EventArgs);
VAR p: SimplePrintout;
s: StreamReader;
begin
p := SimplePrintout.Create();
try
// Always call BeginPrintout!
//
p.BeginPrintout();
// Add our print page handler here
//
Include(p.PrintPage, on_PrintPage);
s := StreamReader.Create('c:\autoexec.bat');
p.WriteString(s.ReadToEnd());
s.Close();
p.EndPrintout();
except
on E: Exception do
MessageBox.Show(E.Message);
end;
end;
Lesson 4.
--------
We already know some methods and some properties of the SimplePrintout
class. But there are other methods and properties you may want to use
as you go.
BeginPrintout - use this call before calling any other methods.
WriteString - lets you print one string at the time. The string
can be as long as you want it to be. It will be
wrapped as necessary. This way you can put your
entire document into one string and send it to
printer with one command.
PageBreak - inserts a page break.
EndPrintout - this will flush data to the physical printer.
AbortPrintout - this will terminate output without printing
to physical device, if called instead of EndPrintout.
Page setup:
NonPrintableGutterSize - measured in inches.
Most printers do not let you print at
the very edge of the page. We set this
non-printable gutter size to 3/16" by default
The programmer can change this setting.
TopMargin - Top margin including the gutter, in inches
LeftMargin - Left margin including the gutter, in inches
RightMargin - Right margin including the gutter, in inches
BottomMargin - Bottom margin including the gutter, in inches
HeaderText - Static text for the page header, this text
can be changed dynamically in an event handler
FooterText - Static text for the page footer, this text
can be changed dynamically in an event handler
There are two areas on the page. One is within the page margins
and another is the page including the margin areas. For the lack
of a better term, these two areas are called Inner and Outer:
InnerBorderPixels - measured in pixels
Thickness of the border inside the margins, in pixels
OuterBorderPixels - measured in pixels
Thickness of the border outside the margins, but still
within the non-printable gutter area.
InnerBorderColor - Color of the border inside the margins
OuterBorderColor - Color of the border outside the margins
InnerBackColor - Background color of the page inside the margins
OuterBackColor - Background color of the margins
Header, Footer, Band properties:
First of all you probably realize that there is a property called
Footer. Then there is a Header. There is also a property called
"Band." All of these properties are of type TBand. TBand represents
a paragraph of text with its own set of parameters.
Header and Footer are probably easy to understand. The Band property
simply means current paragraph. You can set up the current paragraph
font, size, etc., and simply call WriteString(text). The text will
be printed with current settings. Then you change the Band again,
call WriteString() and the text will be printed with new paragraph
settings.
So as you see there are three paragraphs you work with: Header, Footer,
and the current paragraph exposed through the Band property.
A paragraph (or band) has the following properties:
TextAlignment - current text alignment
instructs the simple printout component to switch
paragraph alignment. This property can be changed
in the middle of printing, it will affect subsequent
WriteString() calls.
This property can be set to: baRight, baCentered,
baJustified, and default: baLeft.
TextFont - lets you select and change a font for the body of
the paragraph.
Keep in mind that a paragraph usually consists of a box
(background) and the text (foreground). Box and text can
have their own indents, colors, etc:
BorderPixelSize - paragraph [box] border pixel size
By default this is set to 0, so no box is not
printed. But the box is still there. It has
a white background color. You can get rid of the
box by setting Transparent property to TRUE
Transparent - we just explained this one
BorderColor - paragraph [box] border color
ForeColor - text color
BackColor - paragraph [box] color, background color
IndentLeft - paragraph indents, in inches
IndentTop
IndentRight
IndentBottom
TextIndentLeft - text indents within the paragraph
TextIndentRight
TextIndentTop
TextIndentBottom
Lesson 5.
--------
SimplePrintout also has a couple of Event handlers. Please
take a look at the DemoProj application to see how they are used.
PrintPage event is of type UserPrintPageEvent. It is very similar to
.NET PrintPage event, so that the programmer gets the full control
before printing each page. Pay attention to the second parameter
of type UserPrintPageEventArgs. It has these members:
PageParms: PrintPageEventArgs;
-- this is the original PrintPageEventArgs, we
pass it to the user.
PageNo: Integer; -- (read only) current page count
The following five Boolean members are set to FALSE by default.
However the programmer can set them to TRUE in the event handler
to indicate specific behaviors:
PrintoutLastPage: Boolean;
-- User may set this to TRUE, which means that SimplePrintout
will print this page and then stop printing.
BackgroundHandledByUser: Boolean;
-- If set by user to TRUE it means that SimplePrintout does not
have to paint the page background, user may have added a
background picture, for example.
PageHandledByUser: Boolean;
-- (set by user) SimplePrintout does not paint the current
page user handled the page. Note that it still paints the
header and footer. The next two items let you disable the
header or the footer, or both.
HeaderHandledByUser: Boolean; -- indicates that user handled the header
FooterHandledByUser: Boolean; -- indicates that user handled the header
----------------------------------------------------
Please take a look at the demo project to see the working code. You
may find it easier to cut and paste the code into your project and
build it up from there.
----------------------------------------------------
Enjoy!
Feedback to: alfred@softsci.com
Ref: SimplePrintout for Delphi for .NET (11/19/03)
----------------------------------------------------